البرمجة

استخدام WTForms مع Flask

اخر تحديث 08/06/2025
16 تمت قراءة 5 دقيقة

مدخل إلى استخدام مكتبة WTForms للتعامل مع نماذج HTML في تطبيقات Flask

تعتبر النماذج (Forms) من العناصر الأساسية والهامة في تطوير تطبيقات الويب الحديثة، فهي الوسيلة التي يتفاعل من خلالها المستخدم مع التطبيق سواء بإدخال بيانات أو تنفيذ عمليات مختلفة. عند تطوير تطبيقات باستخدام إطار Flask، يحتاج المطور إلى طريقة فعالة ومنظمة لبناء وإدارة نماذج HTML، وهذا هو الدور الذي تلعبه مكتبة WTForms بشكل بارز.

ما هي مكتبة WTForms؟

مكتبة WTForms هي مكتبة بايثون تهدف إلى تسهيل إنشاء النماذج الإلكترونية والتحقق من صحة البيانات (Validation) بشكل منظم ومرن. توفر WTForms طريقة برمجية لبناء النماذج بدلًا من كتابة شفرات HTML بشكل مباشر، مما يجعل الكود أكثر قابلية للصيانة والتنظيم. بالإضافة إلى ذلك، تدعم المكتبة عمليات التحقق من صحة البيانات المرسلة من المستخدم، مما يساعد في حماية التطبيق من الأخطاء وإدخال بيانات غير صحيحة.

مواضيع ذات صلة

لماذا WTForms مع Flask؟

على الرغم من أن Flask هو إطار ويب خفيف الوزن ويوفر أدوات بسيطة للتعامل مع النماذج، إلا أن WTForms تضيف طبقة قوية من التنظيم والمرونة، حيث تتيح لك:

  • تعريف النماذج باستخدام صفوف Python.

  • تضمين أنواع مختلفة من الحقول (نص، أزرار اختيار، مربعات اختيار، إلخ).

  • تطبيق قواعد تحقق معقدة بسهولة.

  • فصل منطق العرض (HTML) عن منطق التعامل مع البيانات.

  • تحسين تجربة المستخدم من خلال رسائل الخطأ التوضيحية.

تُعتبر WTForms الخيار الأمثل في تطبيقات Flask عندما تحتاج إلى نماذج أكثر تعقيدًا أو عندما ترغب في إدارة النماذج بطريقة احترافية.

كيفية تثبيت WTForms مع Flask

لتبدأ باستخدام WTForms مع Flask، يمكنك تثبيت المكتبة عبر مدير الحزم pip:

bash
pip install Flask-WTF

مكتبة Flask-WTF هي امتداد لـ WTForms مخصص للتكامل مع Flask، ويُفضل استخدامها لأنها توفر تكاملًا مباشرًا مع Flask، بما في ذلك حماية ضد هجمات CSRF (Cross-Site Request Forgery).

إنشاء نموذج بسيط باستخدام WTForms

لنفترض أنك تريد إنشاء نموذج تسجيل بسيط يحتوي على حقلين: اسم المستخدم وكلمة المرور. سنشرح هنا الخطوات الأساسية لإنشاء النموذج واستخدامه في تطبيق Flask.

1. استيراد المكتبات اللازمة

python
from flask import Flask, render_template, request
from flask_wtf import FlaskForm
from wtforms import StringField, PasswordField, SubmitField
from wtforms.validators import DataRequired, Length

  • FlaskForm: هي الفئة الأساسية لإنشاء النماذج في Flask-WTF.

  • StringField و PasswordField: تمثل حقول النص وكلمة المرور.

  • SubmitField: زر الإرسال.

  • DataRequired و Length: نوعان من عمليات التحقق لضمان صحة البيانات.

2. إعداد التطبيق ومفتاح الأمان

python
app = Flask(__name__)
app.config['SECRET_KEY'] = 'your_secret_key_here'

مفتاح السرية SECRET_KEY ضروري لتفعيل حماية CSRF وحماية البيانات.

3. تعريف نموذج التسجيل

python
class RegistrationForm(FlaskForm):
    username = StringField('اسم المستخدم', validators=[DataRequired(), Length(min=4, max=25)])
    password = PasswordField('كلمة المرور', validators=[DataRequired(), Length(min=6)])
    submit = SubmitField('تسجيل')

في هذا التعريف:

  • username و password يمثلان حقول الإدخال.

  • تم ربط حقول الإدخال بمتحققّات (Validators) مثل DataRequired الذي يضمن أن الحقل غير فارغ وLength الذي يتحقق من طول النص.

4. إعداد مسار العرض (Route) في Flask

python
@app.route('/register', methods=['GET', 'POST'])
def register():
    form = RegistrationForm()
    if form.validate_on_submit():
        username = form.username.data
        password = form.password.data
        # هنا يمكنك إضافة منطق حفظ المستخدم في قاعدة البيانات
        return 'تم التسجيل بنجاح!'
    return render_template('register.html', form=form)

  • validate_on_submit(): هي طريقة مدمجة في Flask-WTF تتحقق مما إذا كانت البيانات صحيحة وتم إرسال النموذج.

  • في حالة النجاح، يتم التعامل مع البيانات حسب الحاجة.

5. نموذج HTML لعرض النموذج

يمكن كتابة نموذج HTML باستخدام قالب Jinja2، مثال:

html
html>
<html lang="ar">
<head>
    <meta charset="UTF-8">
    <title>تسجيل مستخدم جديدtitle>
head>
<body>
    <h1>تسجيل مستخدم جديدh1>
    <form method="POST" action="{{ url_for('register') }}">
        {{ form.hidden_tag() }}
        <p>
            {{ form.username.label }}<br>
            {{ form.username(size=32) }}<br>
            {% for error in form.username.errors %}
                <span style="color: red;">{{ error }}span>
            {% endfor %}
        p>
        <p>
            {{ form.password.label }}<br>
            {{ form.password(size=32) }}<br>
            {% for error in form.password.errors %}
                <span style="color: red;">{{ error }}span>
            {% endfor %}
        p>
        <p>{{ form.submit() }}p>
    form>
body>
html>

  • form.hidden_tag() تستخدم لإضافة حقول مخفية مثل token الحماية CSRF.

  • يتم عرض الحقول مع تسمية الحقل ورسائل الخطأ في حال وجودها.

أنواع الحقول في WTForms

توفر مكتبة WTForms مجموعة كبيرة ومتنوعة من الحقول التي تناسب جميع احتياجات النماذج، منها:

نوع الحقل الوصف
StringField حقل نصي بسيط لإدخال البيانات النصية
PasswordField حقل نصي مخفي لكلمات المرور
TextAreaField حقل نص متعدد الأسطر
BooleanField مربع اختيار (Checkbox)
RadioField مجموعة أزرار اختيار (Radio buttons)
SelectField قائمة منسدلة لاختيار عنصر واحد
SelectMultipleField قائمة اختيار متعددة العناصر
DateField حقل إدخال لتاريخ
FileField حقل لتحميل الملفات
SubmitField زر الإرسال

كل حقل يدعم خصائص متعددة مثل الاسم، التسمية، القيم الافتراضية، عمليات التحقق، وغيرها.

التحقق من صحة البيانات (Validation)

توفر WTForms مجموعة واسعة من عمليات التحقق (Validators) التي تساعد على ضمان صحة ودقة البيانات المدخلة، ومن أشهرها:

  • DataRequired: يضمن أن الحقل غير فارغ.

  • Length(min, max): يحدد طول النص المسموح به.

  • Email: يتحقق من صحة البريد الإلكتروني.

  • EqualTo: يتحقق من تطابق قيمتين (مثلاً كلمة المرور وتأكيدها).

  • NumberRange: للتحقق من أن الأرقام تقع ضمن نطاق معين.

  • Regexp: للتحقق من مطابقة النص لنمط معين باستخدام التعبيرات النمطية (Regex).

يمكن استخدام أكثر من عملية تحقق في نفس الحقل، ما يمنح مرونة كبيرة في فرض قواعد الإدخال.

حماية CSRF في WTForms

هجمات تزوير طلبات المواقع (CSRF) من أخطر التهديدات في تطبيقات الويب، وتوفر مكتبة Flask-WTF حماية مدمجة لهذه الهجمات عبر إنشاء رمز توكن مخفي في كل نموذج.

  • يتم تضمين التوكن تلقائيًا عند استخدام form.hidden_tag() في قالب HTML.

  • عند إرسال النموذج، يتحقق Flask-WTF من صحة هذا التوكن، ويمنع طلبات غير مصرح بها.

  • لضمان عمل هذه الحماية يجب تعيين SECRET_KEY في إعدادات التطبيق.

التعامل مع ملفات في النماذج

عند الحاجة إلى رفع ملفات (صور، مستندات)، توفر WTForms حقل FileField، ويتم استخدامه بالتوازي مع مكتبة Flask-Uploads أو أدوات أخرى لإدارة الملفات.

مثال على حقل رفع ملف

python
from flask_wtf.file import FileField, FileAllowed, FileRequired

class UploadForm(FlaskForm):
    photo = FileField('صورة الملف', validators=[
        FileRequired(),
        FileAllowed(['jpg', 'png'], 'فقط ملفات JPG و PNG مسموح بها!')
    ])
    submit = SubmitField('رفع')

هنا نرى أن هناك تحقق للتأكد من وجود ملف وأن نوع الملف ضمن أنواع محددة.

التعامل مع النماذج المعقدة والمتعددة

في تطبيقات الويب المتطورة، قد تحتاج النماذج لأن تكون متداخلة أو تحتوي على مجموعات من الحقول، مثل إضافة قائمة من العناصر.

WTForms تدعم هذه الحالات باستخدام:

  • FormField: لإدراج نموذج داخل نموذج آخر.

  • FieldList: لإنشاء قائمة من نفس نوع الحقول أو النماذج.

مثال بسيط:

python
from wtforms import Form, FieldList, FormField, StringField

class AddressForm(Form):
    street = StringField('الشارع')
    city = StringField('المدينة')

class UserForm(FlaskForm):
    name = StringField('الاسم')
    addresses = FieldList(FormField(AddressForm), min_entries=1)
    submit = SubmitField('حفظ')

يمكن من خلال هذا الأسلوب بناء نماذج معقدة متعددة الحقول بشكل منظم.

تحسين تجربة المستخدم مع WTForms

يمكن دمج WTForms مع مكتبات CSS مثل Bootstrap لجعل النماذج أكثر جاذبية وسهولة في الاستخدام. عبر ربط الحقول بفئات CSS وإضافة تنسيقات لرسائل الخطأ، يمكن إنشاء نماذج متوافقة مع مختلف الشاشات والأجهزة.

مزايا استخدام WTForms في مشاريع Flask

  • تقليل تكرار الشيفرة: تعريف النماذج ككائنات Python يجعل الكود أكثر تنظيماً وأقل تكرارًا.

  • إدارة الأخطاء بسهولة: تقديم رسائل خطأ مفهومة للمستخدم.

  • الأمان: دعم حماية CSRF بشكل افتراضي.

  • مرونة التحقق: إمكانية تطبيق قواعد تحقق مخصصة.

  • تكامل سلس مع Flask: تكامل سهل مع نظام القوالب وطلبات الويب.

ملخص

يعتبر استخدام مكتبة WTForms مع Flask من الطرق المثلى لبناء نماذج ويب قوية وآمنة وسهلة الصيانة. توفر المكتبة إطار عمل متكامل لإنشاء الحقول، التحقق من صحة البيانات، حماية النماذج من الهجمات، والتعامل مع متطلبات النماذج المعقدة. من خلال تعريف النماذج في شكل صفوف Python واستخدام القوالب لعرضها، يمكن للمطورين بناء تطبيقات ويب متقدمة تلبي احتياجات المستخدمين مع الحفاظ على بنية برمجية واضحة ومنظمة.

المصادر والمراجع

يعد هذا الشرح مدخلاً مفصلاً لاستخدام WTForms مع Flask ويشكل قاعدة متينة لأي مطور يرغب في بناء نماذج ويب احترافية باستخدام بايثون.

اخر تحديث 08/06/2025
16 تمت قراءة 5 دقيقة